home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / programming / utilities / isan.lha / ISAN / README < prev    next >
Text File  |  1994-05-22  |  10KB  |  253 lines
  1. ****************************************************************************
  2. *                                       *
  3. *    Conditions of use                ISAN 1.2       *
  4. *    -----------------                --------       *
  5. *                                       *
  6. *    This program has been provided for the enjoyment of the masses.       *
  7. *    It is FREEWARE, but not Public Domain.                   *
  8. *    Since the author doesn't ask for anything in return, the user       *
  9. *    will accept the following conditions:                   *
  10. *                                       *
  11. *    1) In no case whatsoever shall the author be liable for any       *
  12. *       damages, losses etc... due to the use of this program.       *
  13. *    2) Distribution of the program is only allowed subject to the       *
  14. *       following restrictions:                       *
  15. *                                       *
  16. *    2.a) No file part of this distribution will be omitted or       *
  17. *         modified in any way.                       *
  18. *    2.b) None of the files which are part of this distribution       *
  19. *         should be stored on environmentally unfriendly media.       *
  20. *         (e.g. paper! (listings, faxes))                   *
  21. *                                       *
  22. *                    Laurence Vanhelsuwé           *
  23. *                    08-MAR-94               *
  24. *                                       *
  25. ****************************************************************************
  26.  
  27. Program Title : ISAN (Instruction Stream ANalyzer)       (Version 1.2)
  28. --------------------
  29. Author : Laurence Vanhelsuwé
  30. ----------------------------
  31.  
  32. 0. Short description
  33.    -----------------
  34.     ISAN Allows you to monitor a Task's machine code and register usage...
  35.     in real time !
  36.  
  37. 1. Requirements/Installation:
  38.    --------------------------
  39.  
  40.     ISAN Is Kickstart 1.3 compatible.
  41.  
  42.     ISAN Only works on 68020 and upwards machines.
  43.     If you run ISAN on a machine with a 68000 or a 68010 it should
  44.     refuse to do any useful work gracefully.
  45.  
  46.     ISAN Needs one run-time configuration file; the default is called
  47.     "ISAN.config". This configuration file should be located in the S:
  48.     directory or in the current directory when ISAN is invoked.
  49.  
  50. 2. How to use it:
  51.    --------------
  52.  
  53.     ISAN is used to collect machine instruction statistics of any
  54.     Task (or Process) currently running on the machine.
  55.     It allows you to snoop on a RUNNING task and find out which
  56.     instructions it is using ... in real-time !
  57.  
  58.     Since the 680x0 potentially has 65536 different instructions
  59.     (opcodes are 16-bit words) it's impractical to somehow show
  60.     65536 different bargraphs or counters for each possible word.
  61.     (but see option GRAFMAP for an alternative, nevertheless).
  62.     Therefore, you provide ISAN with a list of opcodes that you are
  63.     interested in.
  64.  
  65.     You can specify unique opcodes (like $4E75 for RTS) or an opcode
  66.     template with a mask defining "don't care" bits.
  67.     For example $7000 as the template and $0EFF as the mask encompasses
  68.     ALL possible MOVEQ instructions.
  69.     Have a look at the supplied ISAN.config files for some examples.
  70.  
  71.     ISAN Allows you to analyze the instruction stream in two ways:
  72.  
  73.      - MODE 1 traces every single instruction of a Task
  74.  
  75.      - MODE 2 traces only instructions which cause a change of program
  76.               flow (branches, jumps, ..)
  77.  
  78.     This feature is a direct mapping from the 68020+ dual-mode
  79.     CPU TRACE capability.
  80.  
  81.     The slider gadget at the right of the window determines the update
  82.     speed of the graphs. The higher the slider, the higher the update
  83.     speed. The slowest update speed gives an update every 2.5 seconds
  84.     approximately.
  85.  
  86.     Clicking inside the window will reset the counters.
  87.  
  88.     A full syntax template is produced when passing a "?" as the only
  89.     command line argument:
  90.  
  91.         ISAN ?
  92.  
  93.     Internally ISAN uses a (built-in) clone of the 2.0 ReadArgs()
  94.     routine to parse the command line arguments in a flexible and
  95.     consistent manner (this gives 1.2/1.3 users the uniformity of
  96.     command line templates that 2.0 users are blessed with).
  97.  
  98.  
  99. 3. What can you do with ISAN ?
  100.    ---------------------------
  101.  
  102.     Obviously you need a reasonable knowledge of assembler and/or the
  103.     680x0 microprocessors to get the most out of this system utility.
  104.  
  105.     You can for example easily work out whether a program is derived
  106.     from lean, mean assembler or just from lazy, overweight 'C'.
  107.  
  108.     You can also find out whether the program uses the extra instructions
  109.     and/or addressing modes of the 68020+ CPUs or 6888x FPUs.
  110.  
  111.     You could also possibly detect viruses by spotting strange program
  112.     behavior as reflected by strange instruction usage (the example
  113.     ISAN.config file has an entry to spot short absolute JSRs... there's
  114.     no way a normal program should ever do this; only a virus hiding in
  115.     very low memory (<32K) might use this to conserve code space...).
  116.  
  117.     Basically you can find whether a program uses a certain instruction
  118.     or group of instructions frequently and if so exactly how many times
  119.     etc...
  120.  
  121.     Using the TOTAL switch you can also learn more about your computer
  122.     and go "Geee ! That many instructions for a stupid keypress ?!".
  123.     (The days of a Commodore 64-type OS are definitely over... sniff)
  124.  
  125.     Etc... 
  126.  
  127. 4. Internals:
  128.    ----------
  129.  
  130.     ISAN Works by allocating 65536 counters. One ULONG per possible
  131.     680x0 opcode.
  132.     It just adds a TRACE exception (trap) handler to the target Task
  133.     and enables T1 or T0 in the SR copy of the Task in its saved context.
  134.     The handler just grabs the Instruction Pointer (IP) from the exception
  135.     stack frame, picks up the word pointed to by that IP and increments
  136.     the LONG counter associated with that word (=instruction).
  137.  
  138.     So basically you've got 256K of counters RAM which is updated
  139.     by the Task itself (not ISAN!); while ISAN just lazily sits there
  140.     picking up selected counters specified by your list of opcodes
  141.     and updates the graphs window accordingly.
  142.  
  143.     Note that turning the update speed up to its maximum will only give
  144.     you smooth(ish) evolution of frequencies if the Task being analyzed
  145.     has a task priority lower or equal to that of ISAN (which is normally
  146.     0 if your parent Shell hasn't changed the default by doing a
  147.     settaskpri).
  148.     If you analyze tasks like input.device or scsi.device which both
  149.     have priorities higher than ISAN's then the updating will be jerky
  150.     because ISAN doesn't get a chance to make quick "snapshots" of the
  151.     frequencies while the task is running.
  152.     This is of course due to the higher priority Task blocking ISAN
  153.     from getting a time slice (logical isn't it ?!).
  154.     (This explanation is just for those who might think that ISAN is
  155.     screwing up at high update speeds or something like that! No so.).
  156.  
  157.     When the register option is used you'll find that the PCs of most
  158.     Tasks don't do much. This is not a bug and is again due to the multi-
  159.     tasking nature of the Amiga.
  160.     Tasks which are CPU bound (constantly READY, not WAITING) do have
  161.     PCs which will change frequently in ISAN's register output window.
  162.  
  163. 5. ISAN Limitations/Warnings:
  164.    --------------------------
  165.  
  166. !CRASH!    - Make 300% sure the Task being traced doesn't exit (disappear)
  167.     BEFORE ISAN quits !
  168.     ISAN 1.0 Has no reliable way of knowing whether the Task vanished
  169.     from under its nose or not (the Task TCB might be deallocated and
  170.     then a new Task started with a new TCB in exactly the same spot!).
  171.     The safest way to go about things is to do a NEWCLI and trace that
  172.     newly created Shell in which you can start your program that you
  173.     want to analyze.
  174.     The only downside is that you'll get some garbage readings from the
  175.     CLI process itself just prior to your program taking over the Shell.
  176.     This is of course because the CLI has to load and start the program.
  177.  
  178. !CRASH! - Since ISAN 1.0 adds a trap handler via the TC_TRAPCODE vector,
  179.     programs which make use of the following 680x0 traps will not work
  180.     correctly:
  181.         - Bus Error
  182.         - Address Error
  183.         - Illegal instruction
  184.         - Zero divide
  185.         - CHK
  186.         - TRAPV, TRAPcc
  187.         - TRACE            (! That's the one I use)
  188.         - Line $A opcodes
  189.         - Line $F opcodes
  190.     To be more precise programs will fail if these traps are generated;
  191.     thus CHK and TRAPV instructions cause no problem as long as they
  192.     don't fire.
  193.     Normally all these traps give you a "Software Failure" requester
  194.     anyway, I anticipate problems only when looking at compiled HLL
  195.     code with run-time array bounds or arithmetic overflow checking on.
  196.  
  197.     - If you specify a huge list of opcodes you want to snoop on, ISAN
  198.     might not be able to list them all in a Window (due to the Workbench
  199.     Screen having a finite height), so it refuses to open its window and
  200.     returns an error. (a slider gadget to scroll through a huge list would
  201.     be better - maybe for version 1.1).
  202.  
  203.     - ISAN 1.0 can't look beyond the opcode (the first word).
  204.     So you can't find out if a program uses specific arguments in the
  205.     extra words.
  206.     Arguments encoded in the opcode itself are of course possible.
  207.     E.g. in  MOVE.W    #$BEEF,d0  the immediate operand $BEEF is stored in
  208.     an extra word after the opcode. ISAN has no way of snooping beyond
  209.     the opcode, in other words you can't ask ISAN to find MOVEs with
  210.     immediate operands of xxxx.
  211.  
  212.     - Since ISAN works by enabling the TRACE mode of the target Task
  213.     (and not much more), if a Task is READY all the time (not in the
  214.     Wait()ing queue), then the WHOLE system will get very jerky and
  215.     slow because of the trace exceptions going off all the time.
  216.     Apart from doing fancy re-scheduling in the TRACE exception handler
  217.     there's not much you can do about this.
  218.  
  219.     - When specifying opcode groups (templates) you should know that the
  220.     more "don't care" bits, the more work ISAN will have to do to find
  221.     all the possible opcode combinations.
  222.     For example if your don't care mask contains just 5 set bits, then
  223.     ISAN will have to find 2^5 = 32 unique opcode counters.
  224.     For every update pass ISAN freezes multi-tasking to get a consistent
  225.     view of the counters array (a "snapshot").
  226.     Keep masks reasonable otherwise multi-tasking might get disabled
  227.     for too long (resulting in jerky pointer movement ... at least)!
  228.  
  229. 6. Changes from previous versions:
  230.    -------------------------------
  231.  
  232. 1.2:    - Added simplistic PROFILE option.
  233.       Added FILE option to use files other than S:ISAN.config
  234.  
  235. 1.1:    - Added option to display Task regsisters in seperate window.
  236.  
  237.     - Optimized TRACE handlers to use memory indirect addressing modes
  238.     (which in turn allowed me to optimize the save/restore sequences).
  239.  
  240. 7. Credits:
  241.    --------
  242.  
  243.     Any comments, ideas or bug reports?
  244.     My name and address are:
  245.     
  246.     Laurence Vanhelsuwé
  247.     Christinastraat 105
  248.     B-8400 Oostende
  249.     Belgium
  250.  
  251.  
  252.                             Enjoy !
  253.